.\" portable MARS is
.\" Copyright (c) by Albert Ma, Na'ndor Sieben, Stefan Strack, Mintardjo Wangsaw and Ilmari Karonen
.\"
.\" pmars.6 by Stefan Strack
.\" $Id: pmars.6,v 1.4 2000/12/25 00:49:07 iltzu Exp $
.\"
.\" to create a printable manual with proper pagination do
.\" nroff -man -e pmars.6 > pmars.doc
.\" ex pmars.doc
.\" :%s/_\^H//g
.\" :g/PMARS(6)/-2,-1d
.\" :g/PMARS(6)/+1d
.\" :g/Last change:/-1d
.\" :g/Last change:/+1,+2d
.\" :wq
.de EX      \"Begin example
.ne 5
.if n .sp 1
.if t .sp .5
.nf
.in +5n
..
.de EE      \"End example
.fi
.in -5n
.if n .sp 1
.if t .sp .5
..
.TH PMARS 6 "December 25, 2000" "PMARS v0.9.2"
.ad b
.SH NAME
pmars \- portable corewar system with ICWS'94 extensions
.SH SYNOPSIS
.I pmars
[
.I option \fP...\fI
]
file1
[
.I file(s)
]
.SH DESCRIPTION
.I pMARS
(portable Memory Array Redcode Simulator) is a corewar
interpreter with multi-platform support.
.I pMARS
currently runs on UNIX systems, PC/DOS, VMS, Amiga (AmigaDOS command line),
and the Mac.
.I pMARS
implements the ICWS'94 draft standard, but can also be used in
ICWS'88 mode. The base system includes a graphical core
display for UNIX (curses, X-windows), PC/linux (svgalib), PC/DOS and the Mac
(see APPENDIX). A line-oriented debugger is
included to help in writing warriors for the ICWS'94 draft standard.
.PP
.I pMARS
runs one or more warriors written in
.I Redcode
that are provided as
.I file(s)
on the command line.
Running a single warrior is supported for debugging. Two warriors are
pitted against each other for standard play, but up to 36 warriors can be
named for "multi-warrior" core war. If the warrior(s)
assemble without error they are loaded into the core array and
executed in round-robin mode starting with the first warrior.
Warrior 1 is loaded starting at core position
0, warrior 2, 3, etc., at either a random or fixed position.
For fairness the starting order is rotated after each round.
.SH SCORE
The score is reported after all rounds
have been played. A round ends when either
a single surviving warrior remains or when a maximum number of cycles
has elapsed.  For each round, every surviving warrior is awarded
points calculated from a score formula (F).
By default, this is (W*W-1)/S, where
W is the total number of warriors participating, S is the number of
of survivors, and "/" is integer division. Alternative score formulas can be
specified with the
.I   =
option (see below).
.PP
When two warriors battle, the results are reported as wins1, wins2, and ties,
where wins1 and wins2 are the numbers of rounds that each warrior
won, and ties are the number of rounds in which both warriors lasted until time-out.
The score is then:
.PP
.nf
        warrior 1:  points = wins1 * F + ties * F
        warrior 2:  points = wins2 * F + ties * F
.fi
.PP
F is a score formula containing the W and S parameters.
When more than two warriors (W) participate in a game, results are reported as
wins[1], wins[2], .., wins[W], losses for each warrior, where the index
indicates the number of warriors that survived until the end (S parameter in the score formula). The total number of points for each warrior is then calculated as:
.PP
.nf
        points =  sum (S=1..W) (wins[S] * F)
.fi
.PP
A few alternative score formulas:
.EX
        10
        (W+1)/S
        (x=W-S+1)*(x+1)/2
        (S==3)*5 + (S==2)*3 + (S==1)
        (S == 1)*W + (S != 1)
.EE
.SH OPTIONS
Command line options may occur anywhere on the command line. Single-letter
options without
a parameter can be combined as in \-fbe. The special argument
.I -
(dash) stands for standard input (stdin). It can be combined with the
.I -@
option (see below) to signify reading options from stdin, or the
.I -
can take the place of a  warrior filename, in which case warrior code
starting with a
.I ;redcode
line and ending with an
.I END
statement is extracted from stdin. The
.I END
statement can be omitted if the next
.I ;redcode
line immediately follows the last instruction. Several warriors, each specified
by a separate dash on the command line and bracketed by
.I ;redcode/END
can be piped into
.I pMARS.
.I "#-"
(where # is a positive number) is a shorthand for writing this number of
dashes on the command line.
.TP
.BI \-r\ #
This options sets the number of rounds to play. The default is 1. \-r 0
produces assembly output (unless -b is specified), but does not execute
the warrior(s). A maximum of 32787 rounds can be specified.
.TP
.BI \-s\ #
The \-s option specifies the size of core memory in number of instructions.
It defaults to 8000. Maximum core size is platform-dependent, but usually
at least 65535.
.TP
.BI \-c\ #
\-c sets the maximum number of cycles per round.
A cycle consists of one execution of each warrior. A round ends when either a
single warrior remains executing or when the maximum number of cycles has
elapsed.
.TP
.BI \-p\ #
This option sets the maximum number of processes a warrior can run.
The default is 8000.
.TP
.BI \-l\ #
This sets the maximum length of a warrior source file in instructions.
It defaults to 100 and can be up to 500.
.TP
.BI \-d\ #
This option specifies the minimum distance between the first instruction of
each warrior. It cannot be smaller than the maximum length (-l option) and
defaults to 100 instructions.
.TP
.BI \-S\ #
The -S option sets the size of the P-space to # cells. The default is 1/16th
of core size if core size is evenly divisible by sixteen, or the next larger
divisible fraction. See also the P-SPACE section below.
.TP
.BI \-f
The \-f option instructs the loader to use a fixed series of addresses for
positioning warriors. This is done by initializing the pseudo random number
generator with a checksum value derived from the source of all warriors.
Thus, initial placements will still be "random" from round to round,
but will be the same if the same warriors are run again. As a
consequence, the result of battles
run with the \-f option will show no statistical
fluctuations. This options is useful for validating ports of
.I pMARS
to new platforms and for providing an absolute, albeit arbitrary
performance measure for warriors.
.TP
.BI \-F\ #
This option server two purposes. It sets the seed value of the pseudo
random number generator, and also tells the loader to install warrior
2 at the given address # for round 1. If the number is larger than the
core size minus the minimum warrior distance, it will be wrapped
around to the range of available starting positions.
This option is useful for testing different
versions of a warrior with constant initial placement.
Warrior 1 is always installed at address 0.
The \-F and \-f options are mutually
exclusive. If neither option is specified, the pseudo random number
generator is initialized with the system time.
.TP
.BI \-P
This option makes
.I pMARS
use an alternative algorithm for positioning warriors. This algorithm uses
all possible combinations of starting order and position in a random
sequence, and will not use the same combination twice unless all the
combinations have already been used. If the \-r option is not given, the
number of rounds fought will be the number of all possible combinations.
Trying to use this option with more (or less) than two warriors causes an
error.
.TP
.BI \-e
If this option is specified, the
.I cdb
debugger is entered immediately after
loading warriors into core.
.TP
.BI \-b
This options runs
.I pMARS
in brief output mode. \-b suppresses warrior listings after assembly.
.TP
.BI \-k
With the \-k option,
.I pMARS
uses the same output format as the KotH program. This option enables
.I pMARS
to work with scripts written for the KotH server.
.TP
.BI \-8
This options enforces strict compliance with the ICWS'88 standard and
disables all ICWS'94 language extensions, which are flagged as syntax errors
by the assembler. Since ICWS'94 is a superset of ICWS'88, this options is
not necessary to run ICWS'88 warriors.
.TP
.BI \-o
When this option is given,
.I pMARS
reports scores in decreasing order rather
than in the order warriors were named on the command line. This is mostly
useful for multi-warrior play.
.TP
.BI \-V
The assembler generates verbose output with this option. This is only useful
for debugging.
.TP
.BI \-v
This option sets the display mode for UNIX and DOS display versions (see
APPENDIX).
.TP
.BI \-@\ <fn>
.I pMARS
continues reading options and filenames from the parameter file
.I <fn>.
If
.I <fn>
is a - (dash) standard input is parsed. Comments in the parameter file start
with a semicolon.
.TP
.BI -=\ <string>
The = (equal) option allows you to specify a custom score formula (see
SCORE). The formula may contain the standard arithmetic and logical operators
(as in the C language), as well as the parameters W (number of warriors
participating) and S (number of warriors surviving this round). You need to
enclose the formula string with quotes if it contains spaces or characters
interpreted by the operating system.
.TP
.BI \-Q\ #
The "query" option is intended for use in scripts that run
.I pMARS
in batch mode. Depending on the number code following
.I -Q,
the program returns an informative number as the exit status.
"pmars -Q 1000" e.g. will cause
.I pMARS
to exit with a code that spells out the program version. More on
.I -Q
arguments and exit codes can be found in the ADDENDUM.
.TP
.BI $
The $ (dollar) parameter is not preceded by a dash and cannot be grouped with
other options. It terminates reading command line parameters and is used in
parameter files or input streams
.I (-@ fn).
The
.I $
is necessary if you want to combine two or more of command line parameters,
warrior code and cdb commands in the same input stream or file. Below an example
of such a combined input file:
.EX
    ;Below the command line parameters:
    -r 10 -beF 1000 2- $
    ;redcode
    ;name Imp 1
    ;assert 1
    mov 0,1
    end
    ;redcode
    ;name Imp 2
    ;assert 1
    mov 0,2
    mov 0,2
    end
    !! cdb commands follow:
    sk 1000
    reg
    quit
.EE
.SH X-WINDOWS OPTIONS
The X-Windows display version of pMARS has these additional command line
options:
.PP
.TP
.BI \-display\ <string>
Expects a string specifying the display where the window should appear.
Following X standards, this display specification has a format of
hostname.domain:display.screen where the part before the colon is the
standard internet host specification and display and screen are integers.
The screen specification can be omitted. For an example, consider you
are working at an X terminal named ncd13.complang.tuwien.ac.at and
remotely logged in at host stud1.tuwien.ac.at where the binary of
pmars lies, you can use the following command line
.PP
.nf
  stud1$ pmars -display ncd13.complang.tuwien.ac.at:0 -b aeka.red aeka.red
.fi
  and the window will appear at you local screen.
.TP
.BI \-geometry\ <string>
Lets you specify the initial size and position of the window. The format
is widthxheight+x+y where width, height, x, y are integers and + may be
replaced by -. Either of the two parts (widthxheight or +x+y) may be
omitted. This overrides the -v switch concerning the window
geometry. As an example, pmars -geometry 600x400+30+100 ....
will open a window of 600 by 400 pixels at the screen position (30,100).
pmars -geometry 1024x768 ... creates a window of 1024x768 pixels and
pmars -geometry -20+300 ... creates a window with standard size with its
left upper corner at position (-20,300), i.e. out of the left side of the
screen.
.TP
.BI \-fn\ <string>
The string following this argument specifies the X font to use. By
default, a terminal font is used. If this font can't be found, "fixed"
is used for a font ("fixed" should be present at every X installation).
Use the command 'xlsfonts' to get a listing of fonts that can be used
at your X server. 'xfontsel' provides a comfortable way to select a
font. "fixed" is the fallback if the specified font can't be found.
It is strongly recommended to use a fixed pitch font.
.PP
The argument of the
.I -v
display option has an additional fourth digit in the X-Windows version: 0 
(the default)
enables the color display, 1 the grayscale, and 2 the black and white display
(e.g. -v 1033 for the grayscale display).
.SH REDCODE
.I pMARS
implements an extension of the proposed ICWS'94 standard. The new instruction
modifiers
.I .A,.B,.AB,.F,.X,
and
.I .I,
the arithmetic instructions
.I MUL, DIV
and
.I MOD,
as well as post-increment indirect (>) are supported.
.I pMARS
currently does not implement read/write ranges, although they may be
added in future versions.
.LP
Version 0.5 of
.I pMARS
adds support for three experimental opcodes that are currently not included
in the ICWS'94 draft:
.LP
SEQ (Skip if EQual): this is a synonym for CMP and is included mainly for
clarity (future versions of
.I pMARS
may implement SEQ as a "predefined EQU" rather than a true opcode).
.LP
SNE (Skip if Not Equal): the opposite of SEQ.
.LP
NOP (No OPerations): do nothing.
.LP
Version 0.6 adds three new indirect addressing modes that use the A-field
instead of the B-field as the pointer for indirection:
.LP
* - indirect using A-field
.LP
{ - predrecement indirect using A-field
.LP
} - postincrement indirect using A-field
.PP
The new P-space instructions of version 0.8 are discussed under separate
heading below.
.PP
The assembler also supports multi\-line
.I EQU
statements, a feature not included in the current ICWS'94 draft.
The format for multi-line EQUates is
.EX
    <label> EQU <line1>
            EQU <line2>
            [...]
            EQU <lineN>
.EE
<label> in the warrior source is replaced by <line1> <newline> <line2>
<newline> [....] lineN. In contrast to KotH, pmars
.I EQUs
substitute arbitrary text, and not just expressions.
.I  EQU
expressions are not implicitly parenthesized.
.LP
.I pMARS
features the non-standard
.I FOR
text-repetition macro. 
This macro repeats the text between
.I FOR
and
.I ROF
a specified number of times:
.EX
<labels> <counter> FOR <times>
                   [..]
                   ROF
.EE
<times> is an expression specifying the number of expansions; it may
contain EQUates and labels as long as they have been defined before the
FOR/ROF block.
<counter> is the last label before the FOR word, but not necessarily on the
same line.
It is expanded to 01, 02, ..,
<times> in each repetition. The optional <labels> label the first
instruction after
.I FOR
expansion. An example:
.EX
        ORG start
start
sp      FOR 2
a&sp        SPL a&sp
            JMP a&sp
        ROF

becomes after expansion

start
a01     SPL a01
        JMP a01
a02     SPL a02
        JMP a02
.EE
The symbol & concatenates 'a' and 01, 02 to form a valid label.
.I EQU
expansion and FOR/ROF processing is done in the same pass.
It is therefore possible to write
.EX
dest01  EQU 500
dest02  EQU 1000
dest03  EQU 1500

idx     FOR 3
            MOV src,dest&idx
            MOV src+1,dest&idx
        ROF

src     MOV <-1,<-1
        JMP src,<-2
.EE
Using predefined EQUates (see below) it is possible to define adaptive FOR/ROF
blocks. The next example fills the remainder of the warrior (up to MAXLENGTH lines)
with decoy instructions:
.EX
    FOR MAXLENGTH-CURLINE
        DAT 1,1
    ROF
.EE
Since true logical expressions
have a value of "1" and false expressions a value of "0", you can write conditionally 
assembled code enclosed by FOR/ROF:
.EX
    FOR CORESIZE == 8000
    <some code>
    ROF

    FOR CORESIZE != 8000
    <other code>
    ROF
.EE
.I pMARS
uses KotH-style
.I ;name
and
.I ;author
comments to describe warriors.
If a line starting with ;redcode is present, all text preceding it is
ignored. This makes it possible to run posted warriors without removing
mail headers and descriptive text.
The
.I ;version, ;strategy
and other comments mentioned in the ICWS'94 draft are currently not used.
.LP
As another "non-standard" extension, the assembler predefines the following
run-time variables: CORESIZE, MAXPROCESSES, MAXCYCLES, MAXLENGTH,
MINDISTANCE, ROUNDS, and PSPACESIZE.
They can be used in your
.I Redcode
as though they were defined by EQUs like
.EX
    CORESIZE     EQU 55440  ;current value of -s parameter
    MAXPROCESSES EQU 10000  ;current value of -p parameter
    [etc.]
.EE
The run-time variable CURLINE holds the current instruction number offset
from the first instruction. WARRIORS is initialized with the number of warriors
specified on the command line.
.LP
.I pMARS supports the
.I ;assert
directive as a way of checking whether a warrior is run under the parameters
it was designed for. If the expression following
.I ;assert
evaluates to "0" (false), assembly is aborted with an error message. If an
.I ;assert
is missing, a warning is issued. Examples:
.EX
    ;assert CORESIZE == 55440 && MAXLENGTH >= 200
    ;assert !(CORESIZE % 4)  ; is multiple of 4
    ;assert 1 ; if warrior works under all settings
.EE
The run-time variable VERSION holds the current
.I pMARS
version (e.g. "60" is v0.6.0) and is useful in ;assert expressions.
.\".PP
.\"RANDOM is initialized to a pseudo-random value between 0 and CORESIZE-1
.\"at the start of each assembly, i.e. multiple RANDOM's in your warrior
.\"source reference the same number.  RANDOM can be used randomize boot
.\"distances to thwart specialized attacks, but it is generally not a good
.\"idea to overuse RANDOM as this makes scores less predictable and improving
.\"a warrior design more difficult.
.\"A possible use for RANDOM is for empirically determining optimal scanning
.\"or bombing constants.
.PP
With the \-8 option,
.I pMARS
is fully ICWS'88 compatible, except that a comma is required between
operands. Extensions like predefined and multi-line EQUs and FOR/ROF are
supported even in ICWS'88 mode.
.LP
A full treatment of corewar and ICWS'94 in particular is beyond
the scope of this document. General information about corewar as well as
the ICWS'94 draft is available by anonymous FTP from soda.berkeley.edu in
pub/corewar.
.SH P-SPACE
Originating from discussions on rec.games.corewar, P-space is an
attempt at making warriors more "intelligent" by giving them a memory.
P-space, short for "private", "permanent" or "priviledged" space is a
memory area separate from core whose contents is not cleared between
rounds. Every warrior has its own P-space for gathering information
about the opposing warrior, but there is a provision for sharing
P-space in team play (see below).
.PP
P-space cells contain values in the range 0..CORESIZE-1. The number of
P-space cells can be adjusted with the -S command line option; by
default, P-space size is 1/16th of CORESIZE. This number is available
to warriors as the predefined variable PSPACESIZE.  pMARS updates
P-space cell 0 at the beginning of each round with the result of the
previous round: 0 signifies a loss in the previous round, a number
larger than zero means that the warrior survived until the end of the
round, the value indicating the number of surviving warriors. That is,
a value of "1" means that the warrior survived by itself (a "win" in
a two-warrior battle), a value of "2" that two warriors lasted until
the end (a "tie" in a two warrior battle), etc..
In the first round, P-cell 0 is set to -1 (actually CORESIZE-1) to
indicate that there is no previous result.
.PP
There are two new instructions for accessing P-space:
.PP
.TP
.BI LDP
(Load P-space) loads P-space cell specified by A-value into
core at B-address.
.TP
.BI STP
(Store P-space) stores A-value into P-space cell specified by
B-value.
.PP
It is important to note that P-space cells are refered to by
A/B-values as opposed to A/B-addresses. As an example,
"STP #9,#1" stores number 9 in P-cell 1.
.PP
Since all P-space access is only via these two instructions, it takes
too much time and space to use P-space for working variables where
they would be safe from the opposing warrior. P-space was made 
deliberately hard to access, unlike a set of general purpose 
registers.
.PP
P-space can also be used for communication between warriors belonging 
to a team in multi-warrior core war. To allow communication, P-space
has to be declared as "shared". You do this by including the PIN
pseudo-opcode in your source:
.PP
.TP
.BI PIN
(P-space Identification Number) has a single numerical
argument. If two or more participating warriors have the same
PIN argument, they share the same P-space. If the PIN
pseudo-opcode is missing from a warrior's source, its P-space
is strictly private. The PIN argument is not normalized to
[0..CORESIZE-1] before comparison. "PIN 0" and "PIN
CORESIZE" are therefore not the same.
.PP
P-cell #0 holding the result of the last round is exempt from sharing,
i.e.  every warrior has its own last round cell even though the rest
of its P-space may be shared.
.PP
.SH CDB DEBUGGER
.I Cdb
is a line-oriented debugger. It is invoked either by specifying the
\-e option (enter
.I cdb
immediately), by including debugging commands in
the warrior source, or by hitting Ctrl-C during the simulation.
The debugger is also entered whenever a warrior terminates ("post-mortem")
if execution was started with the
.I go
command.
.I cdb
is very powerful and has an overwhelming number of commands. You may want to
start with only the most often used commands:
.I step
(single step execution),
.I go
(execute until breakpoint),
.I list
(look at core),
.I trace
and
.I untrace
(set and remove breakpoints),
and go on to more complex ones later.
.LP
The following commands are available at the
.I cdb
prompt; commands can be abbreviated to the first unambiguous substring.
.TP
.BI <Enter>
repeats the last command issued at the
.I cdb
prompt.
.TP
.BI help
displays a brief command summary.
.TP
.BI progress
displays the status of the current game in progress.
.TP
.BI registers
displays the current state of the simulator, including program counters
and task queues.
.TP
.BI go
runs the simulator until an instruction whose trace bit
is set is executed. If there are no traced instructions
.I go
returns to the post-mortem debugger.
.TP
.BI step
executes the next instruction in the task queue and returns to the
.I cdb
prompt.
.TP
.BI continue
returns to the simulator to complete the game
without interruptions.
.TP
.BI thread
is similar to
.I step
except that only the current task thread is traced.
.TP
.BI skip\ [count]
executes the next
.I [count]
instructions in the queue silently before returning to the
.I cdb
prompt.
.TP
.BI execute\ [address]
resets the task queue of the current warrior to
.I [address]
and executes it. This is useful in conjunction with
.I edit.
.TP
.BI quit
aborts
.I pMARS
and returns to the OS prompt.
.TP
.BI trace\ [range]
sets the trace bit of the specified address or address range.
.TP
.BI untrace\ [range]
clears the trace bit of the specified address or address range.
.TP
.BI moveable\ on|off
specifies whether the trace bit is copied by the
MOV.I instruction. The default is on.
.TP
.BI list\ [range]
displays the specified range of core addresses, a set
trace bit is indicated by 'T'.
Unmodified addresses (DAT.F 0,0) are shown as blank.
.TP
.BI edit\ [range]
allows modifying core. The specified addresses are edited by typing in
new instructions. Typing one or more spaces leaves the core address
unchanged, just hitting <return> repeats the last input, and
a syntax error aborts the edit. The full
.I Redcode
syntax including labels and (multi-line) EQUates can be used. Label and
EQUate definitions remain in effect until the program terminates.
The
.I edit
command is useful for modifying warriors and trying out
single instructions without having to exit and restart
.I pMARS.
.TP
.BI fill\ [range]
is similar to
.I edit.
Instructions in the specified range are replaced by one
typed in instruction. Entering DAT.F 0,0 ,e.g. clears the address range.
.TP
.BI search\ [pattern]
searches core instructions for
a text pattern in the forward direction. The next
instruction matching [pattern] is displayed. The search includes the address
number and trace symbol (T),
is case- and space-insensitive and may contain wildcards: * (asteriks)
matches any number of characters; ? (question mark) matches exactly one
character. E.g. "search ," searches for the next non-blank address;
"search dat*, ?0t" searches for the next DAT instruction that is traced and
has a zero B-operand value, regardless of modifier, A-operand and B-mode.
.TP
.BI write\ [file]
opens a file for logging subsequent
.I cdb
output to. The logfile is closed by issuing
.I write
without an argument.
.TP
.BI echo\ [string]
is used mostly inside macros. [string] is echoed to the screen followed by
<newline>.
.TP
.BI remark\ [string]
is ignored by
.I cdb
and can therefore be used to comment macros.
.TP
.BI cls
clears the screen. The no-display UNIX version does this by echoing
an ANSI escape sequence; if this doesn't work for you,
you need to change the CLRSCR string in config.h and recompile.
.I "clear"
is a synonym for
.I "cls".
.TP
.BI display\ clear|on|off|nnn
(available in display versions only) allows clearing the core display
.I (display clear)
or changing the display mode.
.I "display on"
changes the display to the default mode,
.I "display off"
(same as
.I "display 0")
suspends all display updates, and
.I "display nnn",
where nnn is a 1 to 3-digit number, sets the display to this
mode. "nnn" is interpreted like the parameter to the
.I -v
command line option (see APPENDIX).
.TP
.BI switch\ [1|2]
(available in display versions only) makes the left (1) or right (2) panel 
the current panel for
.I cdb
output. Without a number argument
.I switch
changes to the other panel. If the right panel doesn't exist (initially, or 
after
.I close, see below), it is created first.
.TP
.BI close
(available in display versions only) closes the right
.I cdb
panel (if it exists) and makes the left panel fullscreen.
.TP
.BI calc\ expr1[,expr2]
is a command line calculator. Since
.I calc
has no side-effects other than echoing the result of expression 1 (and
expression 2 if provided). In the context of
.I cdb 
macros it is also used to assign values to the register
variables 'c' through 'z'.
.TP
.BI macro\ [name][,file]
loads, executes or lists macros. A macro expands to one line of cdb commands
separated by the tilde character (~) (a so-called command chain, see below).
The command
.I "macro name"
executes the macro "name"; if "name" is left out,
all currently available macros are listed.
.I "macro name,file"
loads macro
definitions from file "file" and executes macro "name"; again, if "name" is
missing, only a listing is produced. Macro definitions are appended to the
list of previously loaded definitions or replace a previously loaded macro
definition with the same name. If you are trying to execute or list macros,
but no macros have been loaded yet, the default macro file "pmars.mac" is
loaded automatically. The special macro file "user" can be specified to input
macro definitions directly from the keyboard. Macro definitions consist of a
macro name, followed by the equal sign, followed by a command (chain).
The macro name can consist of any printable character excluding <space> and
comma; the equal sign is only allowed at the end of a macro name.
Individual macro lines have a limit of 80 characters, but
macro calls inside macro expansions are allowed.
.I Cdb
can hold up to 200 macros in memory.
See also the section on
.I cdb
macro programming below.
.TP
.BI if\ <expression>
controls execution of commands in macros or command chains. If
.I <expression>
evaluates to zero, the next command block is skipped. A command block
consists of either a single command or any number of commands bracketed
by !! (loop start) and ![e] (loop end, see section on macro programming
below).
.I <expression>
may contain C-style comparison and boolean operators (see below).
An
.I if
immediately preceeding a loop end (![e]) can skip out of the loop.
.TP
.BI reset
is used inside macros in conjunction with
.I if
to terminate macro execution, e.g. inside an infinite
loop (...~if A==0~reset~...~!).
.TP
.BI pqueue\ [1|2|..|off]
switches
.I cdb
into "process queue mode". In this mode,
.I list, edit
and
.I fill
operate on the process queue instead of the core array, i.e. you can
view and modify the process queue as easily as the core array. This is
especially useful for debugging complicated multi-process warriors.
.I pqueue
without argument uses the process queue of the current warrior. With
argument 1,2,..,
.pqueue
uses the process queue of warrior 1,2,.., respectively.
.I pqueue off
returns to normal mode.
.TP
.BI wqueue\ [off]
stands for "warrior queue" and is similar to
.I pqueue,
except that numbers provided as arguments for
.I list, edit
and
.I fill
now refer to warriors: "list 0" now shows the program counter of warrior 1,
"list 1" that of warrior 2 and so on.
.I wqueue off
returns to normal "address mode".
.TP
.BI pspace\ [1|2|..|off]
complements the
.I pqueue
and
.I wqueue
commands. If a number is specified, the P-space of that warrior is selected
for viewing/editing. Without an argument, the P-space of the currently
executing warrior is selected. "pspace off" returns to core mode.
.PP
.I go, step, continue
and
.I thread
may have a single address argument. The program counter of the current
warrior is set to this address before execution continues.
.LP
The range argument of the
.I list, trace,
etc. commands has the format <start>,<stop>. Addresses <start> and <stop> are
numbers, special symbols or C-style expressions including special symbols.
If either <start> or
<stop> is omitted, it defaults to the current address.  If both are omitted,
the range of the last
.I cdb
command is used. A single
address (without the comma) acts on only that address. Addresses
starting with a + or - are interpreted relative to the current address.
.PP
Expressions may contain the arithmetic operators -,+,*,/,% (modulo), the
comparison operators ==, !=, <=, >=, and the boolean operators && (AND), ||
(OR), and ! (negation).
Expressions may also include register variables C
through Z and the assignment operator =. Operator precedence is like that
of the C-language and may be overridden by parentheses. Assignment,
comparison and boolean operations are mostly used with
.I calc
and
.I if
commands in macros, but can also be used in Redcode operands.
.PP
Special address symbols used in
.I cdb
commands:
.PP
.nf
 \.     (dot) is the current address (displayed last).
 $     (dollar) is the last core address.
 A     is the A value of the current instruction.
 B     is the B value of the current instruction.
 PC    is the program counter of the currently executing warrior.
 PC1   is the program counter of warrior 1.
 PC2   is the program counter of warrior 2.
 LINES is the number of lines available to the cdb display
 CYCLE is the current execution cycle (counted down)
.fi
.PP
In process queue (pq), warrior queue (wq) or pspace (ps) mode (see
.I pqueue, wqueue, pspace),
most of these symbols have a different meaning:
.PP
.nf
 \.     (dot) is the current process number (pq),
       warrior (wq), or P-space cell (ps) which was displayed last.
 $     (dollar) is the last process in the process queue (pq),
       the last warrior (wq), or the last P-space cell (ps).
 A     is the A value of the instruction of the current process (pq),
       the next executing process of the current warrior (wq), or
       the P-space selector (ps, same as warrior number if unshared).
 B     is the B value of the instruction of the current process (pq),
       the next executing process of the current warrior (wq), or
       the P-space selector (ps).
 PC    is 0.
 PC1.. are 0
.fi
.PP
Preceding a command with the character '@' (ampersand)  will suppress
its screen output, but not output to a logfile.
Preceding a command with '&' will suppress both screen and logfile output,
which is useful if you are only interested in the "side-effects" of a 
command.
Starting a command
with a <Space> character suppresses saving it to the "last-command"
buffer that is recalled by <Enter>.
.SH COMMAND CHAINS AND MACRO PROGRAMMING
Several commands can be issued on one line
when separated by the tilde character (\~). These "command chains" are
useful for repeating long command sequences, since <Enter> recalls
the entire chain (see the examples below).
Commands requiring user intervaention
.I (list, edit, fill)
also read their input from the chain.
.LP
The "empty command" (two consecutive tildes or a
tilde at the end of the chain) repeats the last command in the chain.
A command consisting of <Space> is a null command and is used to
simulate pressing <Enter> in
.I list, edit
and
.I fill.
.LP
The exclamation mark (!) character is a special "chain repetitor"
command. The optional expression following '!' specifies how many times
the command chain starting at the beginning of the line or the last
\'!' is executed. '!' without an expression repeats until the program
terminates.
.LP
The symbol '!!' is used for nested loops and marks the start of a command
block to be repeated. The command block is closed by '![expression]' and may
contain other command blocks. A command block immediately following an
.I if
command is executed only if the condition is true.
.PP
With loops, subroutines (macros calling macros), variables (C..Z), 
expressions involving comparisons and boolean operations, and conditional
execution
.I (if),
the
.I cdb
command language can be used to construct complicated macros for
e.g. executing a warrior until a certain core address has changed,
controlling
the 2-panel display, automatically finding the right constants for a warrior,
etc. See the file "pmars.mac" for examples.
.SH EXAMPLE CDB COMMANDS
.TP
.BI list\ ,+20
lists the next 20 instructions.
.TP
.BI trace\ pc-10,pc +10
traces 21 addresses centered around the program counter of the
currently executing warrior.
.TP
.BI untrace\ 0,$
clears all trace bits.
.TP
.BI go\ \~\ reg\ \~\ l+a,+b
chains these commands: execute until the next traced address or
end of round, display the simulator status and list addresses in the
range A-number to B-number of the current instruction.
.TP
.BI @fill0,100\~dat.f\ 0,0
fills addresses 0 through 100 with 'dat.f 0,0', not echoing the
changed addresses to the screen.
.TP
.BI write\ trace.log\~step\~!
produces a continuous execution trace by repeating
.I step
until
.I pMARS
terminates, saving the output to logfile "trace.log".
.TP
.BI @l\ x=5\~!!\~@ed\ x~dat\ x,0\~if\ (x=x+1)<$+1\~!
This command chain could be useful for debugging a stone-type, self-modifying
warrior, which is assumed to occupy address 0 through 4 in this example. The
command fills core starting at address 5 with "dat 5,0", "dat 6,0", a.s.o., so
that you can tell where a bomb which overwrites the warrior came from. To save
some typing, you can turn this command into a macro (foo=@l x=5~..). This is
how it works, step by step:
Assign 5 to register x and make it the current address (@l x=5). Start a
loop (!!) and change address x to "dat x,0" (@ed x~dat x,0). Increment x,
if x is then smaller than the core size ($+1), continue looping
(if (x=x+1)<$+1~!). The '@' in front of the
.I list
and
.I edit
commands suppresses screen output.
.TP
.BI @s\~@4\~if\ b<2\ ||\ b>=$-3\~reset\~!
This command executes a warrior until the B-field of address 4 points
to address 0 through 5: Step and make address 4 the current address
(@s~@4). If the B-field is less than 2 or greater than or equal to
7996 (CORESIZE-1-3) stop execution, else continue looping (if b<2 ||
b>=$-3~reset~!).
.SH SOURCE DEBUGGING DIRECTIVES
Trace bits can also be set by including debugging commands in the
warrior source. A comment format is used to retain compatibility with
simulators that do not support source-embedded debugging commands.
.TP
.BI ;debug\ [static/off]
This command enables/disables all subsequent source-embedded commands.
It is used for commenting out other source comments.
.I ;debug\ static
has
the same effect as the command
.I  moveable off
at the
.I cdb
command prompt.
.I ;debug
is implicitly added in front of every warrior. The
last
.I ;debug
or
.I ;debug static
encountered specifies whether the trace bit is copied by a MOV.I
instruction or not.
.TP
.BI ;trace\ [off]
.I ;trace
starts setting the trace bit with the next instruction until EOF
or a
.I ;trace off
command is encountered.
.TP
.BI ;break
sets the trace bit of the next instruction.
.SH FUTURE DIRECTIONS
We will be glad to assist
in porting
.I pMARS
to other, currently unsupported platforms. This program is still under
development and we will continue to enhance functionality and speed, as well
as adapt to changes in the proposed ICWS'94 standard. If there is demand,
future versions of
.I pMARS
will also implement read/write ranges
.SH BUGS
None whatsoever (right).
Contact for bug reports and suggestions is Stefan Strack
(stst@vuse.vanderbilt.edu).
Please be detailed and include a logfile of the
.I cdb
session if applicable. Bug reports and suggestions concerning the Macintosh
display and interface should also be directed to Alex MacAulay
(macaulay@mundil.cs.mu.oz.au).
.SH AUTHORS
The
.I portable MARS
project was initiated after discussing the ICWS'94 draft on the
rec.games.corewar newsgroup. We realized that we needed a portable
system to try out the proposed standard and to accept, modify or reject it.
The people who started
.I portable MARS
and are responsible for the base code as well as the DOS and UNIX displays
are:
.PP
.nf
Albert Ma (ama@athena.mit.edu)
Nandor Sieben (nandor.sieben@asu.edu)
Stefan Strack (stst@vuse.vanderbilt.edu)
Mintardjo Wangsaw (wangsawm@csos.orst.edu)
.fi
.PP
Alex MacAulay (macaulay@mundil.cs.mu.oz.au) wrote the Macintosh display version.
Martin Maierhofer (m.maierhofer@ieee.org) contributed the linux SVGA and
X windows display.
Nathan Summers (00ncsummers@bsuvc.bsu.edu) did the port to VMS.
.SH ACKNOWLEDGMENTS
We thank Planar (Damien.Doligez@inria.fr) for expert help with debugging and
porting
.I pMARS
to different UNIX machines. We also appreciate the help of Chris Lindensmith
(lind0014@student.tc.umn.edu) and Pierre Baillargeon (dak@info.polymtl.ca)
with the initial Mac and Amiga ports respectively.
Mark Durham (durham@ricevm.rice.edu) spearheaded development of the ICWS'94
draft and we thank him for writing the sample interpreter code included
with the draft.
.SH APPENDIX
.SH PMARSV
.I pMARSv
is a DOS version of
.I pMARS
with a graphical core display. You can chose between EGA/VGA graphics
or text mode with the
.I -v
command line options or by pressing 'v' during the game. The
.I -v
option takes a three digit argument 'xyz'. Digit 'x' specifies the initial
display speed and ranges from 0 (fastest) to 7 (slowest). 'y' is the initial
display mode: 0 for text mode, 1 for standard VGA graphics,
2 and 3 for SVGA, 4 and 5 for EGA, and 6 for CGA graphics.
.PP
The display level 'z' specifies how much is displayed:
.TP
.BI 0
Display nothing. This greatly speeds up execution, especially when in
graphics mode.
.TP
.BI 1
Display execution of addresses. In text mode, a black '0' on blue
background is shown for warrior 1, a black '1' on green for warrior
2, a.s.o.. Numbers blink in white when a DAT instruction is executed. In
graphics mode, a blue square represents warrior 1, a green square
warrior 2, a.s.o.. These colors are also used for other core accesses.
.TP
.BI 2
Also display write accesses. In text mode, they appear as dots; in
graphics mode, they appear as two pixels, offset diagonally.
.TP
.BI 3
Also display decrements and increments. They are shown as '+' and '-'
in text mode and as two pixels offset vertically or horizontally in graphics
mode.
.TP
.BI 4
Also display read accesses, which appear as small dots in text mode and as
single pixels in graphics mode.
.LP
The more is displayed, the slower runs the simulation.
The argument for
.I -v
defaults to 103, i.e. speed=1, mode=text, level=3.
.LP
The text mode display is very fast, but contains less on-screen information
than the graphics display. The core display and the
.I cdb
debugger run full-screen on separate display pages.
.LP
In graphics mode,
core and debugger share the same screen. The mouse can be used to
navigate around core when debugging is enabled: clicking a
mouse button on any core location lists addresses starting there. The
mouse cursor follows the current program counter when in single step mode.
.LP
In both graphics and text mode, the cdb display can be divided into two
side-by-side panels. You can switch between panels with the
.I switch
command (or the <Tab> macro) and close the right panel with
.I close
(or the <Shft-Tab> macro).
Extended (function keys, arrow/page keys, ALT keys, etc.) and control keys
generate macro calls at the
.I cdb
prompt; some of these "hot key macros" have been defined in
"pmars.mac"; you can easily change them or add more with a text editor.
E.g. <PgDn> and <PgUp>
keys currently invoke macros that scroll through core one screen at a time.
.PP
A white line at the top of the display, called the time meter,
indicates the time required to finish the   
current simulation. The amount of time depends on the number of
warriors still alive in the arena. After a warrior dies it no longer 
needs simulation time so the required time to finish the simulation becomes
less. On the time meter this is indicated by a discontinuity. One can 
count the number of dead warriors in the arena by counting the number of
discontinuities on the time meter.     
.PP
Just below, the length of
"process meters" in the color of the warriors they represent show how many
processes each warrior has running.
.LP
The following keys are available at the core display screen:
.TP
.BI 0..4
selects the display level (see above).
.TP
.BI v
switches from text display to graphics display and vice versa.
.TP
.BI >
increases the display speed.
.TP
.BI <
decreases the display speed. The current speed is indicated by a red
bar in graphics mode.
.\".TP
.\".BI s
.\"switches to single step display mode. "Step" on the graphics menu bar is
.\"highlighted in red when in single step mode.
.\".TP
.\".BI <enter>
.\"returns from single step to full speed display.
.TP
.BI d
enters the
.I cdb
debugger. "Debug" on the graphics menu bar is highlighted in red inside
.I cdb.
.TP
.BI <space>
(also 'r') refreshes the core display.
.TP
.BI <escape>
(also 'q') exits to DOS.
.LP
You can define additional keys and commands associated with them by defining
"key-x" macros ("x" is any printable character). E.g.:
.EX
key-p= progress~registers~continue
.EE
Function-key and other macros can also be invoked from the core display.
.SH CURSES DISPLAY
The curses display is very similar to the DOS text mode display. There are
separate pages for core and debugger.
There is a status bar at the bottom of the core display:
.PP
.nf
Rave [0]: 1        Lucky 3 [1]: 3702  Cycle: 72967  R: 2/5 (0 0 1)
.fi
.PP
The display symbol that indicates execution is shown in brackets after the
warrior name. The number after the colon shows the number of processes active.
The "2/5 (0 0 1)" means that this is round 2 of 5; the result so far is one
tie. Only cycle and round information is shown if more than two warriors are
run.
.LP
There is no "hot key" user interface
during the core display, but you can enter the debugger by hitting Ctrl-C
and clearing the display, changing the display mode, etc. from within
.I cdb.
Only the first and third digit of the
.I -v
option and
.I "display"
command argument, namely the display speed and level, have an effect (see
PMARSV above). The display speed setting (0=fastest, 7=slowest) adjusts the
screen refresh rate; depending on the size of your display, movement in
core may appear "jerky" at fast speeds.
Control keys at the
.I cdb
prompt generate a macro call like in the DOS versions.
.PP
If you redirect standard input (by supplying a '-' filename or parameter file),
all interactive input is disabled.
.SH MACINTOSH DISPLAY
.I MacpMARS
is a Macintosh version of
.I pMARS
with a graphical core display
and standard Macintosh user interface. It has two windows, the Core
window and Text window. The display of the core uses four patterns for
each warrior (black and white backgrounds respectively) to show what is
happening in the core:
.PP
\'/' when the core location is written to (including incrementing and
decrementing);
.LP
\'\\' when a process has died at the core location;
.LP
\'-' when a process has executed at the core location;
.LP
\'|' when a process is waiting to execute at the core location.
.PP
If you click on a core location in the Core window while a battle is being
run, the contents will be displayed in the Text window.
.PP
Two warriors can be in memory at any one time. To assemble a warrior
choose "Choose Warrior n..." from the File menu. To remove the warrior
from memory choose "Remove Warrior n...". You can modify the settings
used by choosing "Preferences..." (this can only be done when no battle
is being run). Alternatively, you can type in a command line in the same
way as if you were typing from a unix prompt (if you're used to that sort of
thing) by choosing "Command Line...". The Edit menu is just the normal
Macintosh Edit menu and can be used to cut and paste text in the Text window
and dialogs. The items in the Play menu are fairly self-explanatory: "Go" starts
(or continues) a battle; "Step" executes one instruction and enters the debugger;
"Halt" halts the battle and enters the debugger; "Abort" aborts the battle. The
Window menu is used to show and bring either of the two windows to the front of
the screen.
.PP
The
.I cdb
commands
.I display, switch
and
.I close
are not available in MacpMARS.
.PP
Note: to use very large core sizes (up to about 65000) and process limits
you may need to increase the memory partition for MacpMARS.
To do this, choose "Get Info" from the File menu in the Finder and set the preferred memory size to about 1200K.
.SH EXIT CODES
The following is mainly useful for people who write scripts or batch files
for
.I pMARS.
Upon normal exit, the program returns 0. Below is a listing of what the abnormal
exit codes mean. Your operating system may not support negative exit codes;
in this case you have to convert the value to its unsigned counterpart.
.PP
.nf
    -4      graphics error
    -3      trying to execute 80386 code on a lesser processor
    -2      memory allocation error
    -1      serious program logic error, contact developers
     1      file not found
     2      command line error
     3      assembly error
     4      user aborted program
.fi
The exit codes of the VMS version conform to the VMS standard. The
.I -Q (Query)
command line option (see OPTIONS) allows you to customize the
.I pMARS
exit code. E.g. "pmars -Q 1000" returns the current
.I pMARS
version. Below the -Q arguments and what the resulting exit codes mean.
.TP
.BI 1..W
exit code is score of this warrior, 1: first in result output, 2:
second, a.s.o.. If the -o option is also given, "1" gives the score
of the highest scoring warrior, etc..
.TP
.BI 101..1W
returns the number of this warrior in the result output. Usually -Q 101
returns 1, -Q 102 returns 2 etc., so this is not very useful. If you also
specify the "-o" (order results) option, -Q 101 returns the position of the
highest scoring warrior on the command line, -Q 110 the position of the
10th highest scoring warrior, etc..
.TP
.BI 1000
exit code is the
.I pMARS
version in the same format as the predefined VERSION variable.
.TP
.BI 1001
returns the
.I pMARS
"variant": 0 if the program was compiled with the SERVER option (no debugger),
1 with debugger but without display, 2 with debugger and core display.
.TP
.BI 1002
returns a combination of version and variant: 10*variant+version.
.TP
.BI 1003
the exit code is the core address size in bytes. On a 32-bit CPU, this is
sizeof(int), usually 4. With SMALLMEM compilation, core address size is
sizeof(unsigned short), usually 2.
.TP
.BI 2000
returns how many warriors share one or more P-spaces. A value of 4, e.g.
means that either four warriors share one P-space, or that two pairs of
warriors share two P-spaces.
